Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 011 / templ200.arc / TEMPLATE.DOC < prev next >

Wrap

Text File | 1986-01-13 | 46.0 KB | 1,171 lines

TEMPLATE (tm) Applications Integrator Version 2.00 Copyright (c) 1985 Atkinson, Campbell Developement User Guide TEMPLATE (TM) TEMPLATE (tm) Applications Integrator Version 2.00 Copyright (c) 1985 Atkinson, Campbell Developement Table of Contents 1.0 Description of TEMPLATE 1.0.1 What TEMPLATE Does 1.0.1.1 The Real Time Clock (TOD Block) 1.0.1.2 The MacroKeys (tm) Desktop Facility 1.0.1.3 Customizing with Configuration Files 1.0.1.4 Autoconfiguration for Turnkey Applications 1.0.1.5 The DosShell (tm) Applications Interface 1.1 Installation of TEMPLATE 1.1.1 Distribution Files 1.1.2 Copying Execution Time Files to Another Disk 1.1.3 Hardware Requirements for TEMPLATE 1.1.4 Registration for User Supported Software 1.2 Starting and Stopping TEMPLATE 1.2.1 TEMPLATE Command (Starting) 1.2.2 The F3 Key (Stopping) 1.3 The TEMPLATE Master Menu Screen 1.3.1 The Guest Application Menu 1.3.1.1 Unconfigured Mode 1.3.1.2 Configured Mode 1.3.1.3 Selecting a Guest Application to Run 1.3.2 The TEMPLATE Control Functions Menu 1.3.2.1 F1 - Load a Configuration File 1.3.2.2 F2 - Load a MacroKey Definition File 1.3.2.3 F3 - QUIT TEMPLATE 1.3.2.4 F4 - TOD Block Control 1.3.2.5 F5 - Execute Any DOS Command 1.3.2.6 F6 - Delete Configuration Tables 1.3.2.7 F7 - Delete MacroKey Tables 1.3.2.8 F8 - HIDE TEMPLATE (Stay Resident) 1.4 Using TEMPLATE Configuration Files 1.4.1 AUTOLOAD.COM and CONFIG.CFG Files 1.4.2 LDTCFG.COM and Configuration Files 1.4.3 Structure of .CFG Files 1.4.3 Syntax of Configuration Statements 1.5 Using the MacroKeys Facility 1.5.1 LDMKEY.COM Utility 1.5.2 Structure of .KEY Files 1.5.3 Syntax of MacroKey Redefinition Statements 1.5.4 Advanced Use of MacroKey Definitions 1.6 Programming the DosShell Interface 1.6.1 Theory Behind the DosShell Interface 1.6.2 Programming Requirements 1.6.2.1 Screen Disposition During Execution 1.6.2.2 Invoking Interrupt 63H(ex) 2 TEMPLATE (TM) 1.6.2.3 RAM Requirements, System and User 1.6.3 Invoking From Assembler Routines 1.6.4 Invoking From Turbo Pascal 1.6.5 Invoking From BASIC/BASICA 1.6.6 Stacking Applications in RAM with the DosShell 3 TEMPLATE (TM) 1.0 Description of TEMPLATE 1.0.1 What TEMPLATE Does TEMPLATE is an applications integrator. Its basic function is to provide single keystroke access to applications programs and packages of your choosing, and to bring them together as a coherent, integrated package, customized the way you want it. TEMPLATE also provides a number of other related services described below. 1.0.1.1 The Real Time Clock (TOD Block) As a convenience, TEMPLATE provides a real time clock showing hours, minutes, and seconds. It is also referred to as the TOD block. The TOD block may be turned on or off, and it may be positioned anywhere on the screen. Its default position is the top right corner of the screen. 1.0.1.2 The MacroKeys (tm) Desktop Facility The MacroKeys Desktop Facility is a RAM resident keyboard redefinition facility, with which you can assign a single keystroke to mean (and to input) anything you wish; it is a keyboard macro facility. There is no limit to the number or identity of the keys which may be redefined, as long as the 4096 byte translation table does not overflow. A single key may be redefined as a string of characters up to 255 bytes long. MacroKeys runs transparent to guest applications, operating by intercepting requests for keyboard input at the ROM BIOS level. With the HIDE function described below, TEMPLATE as a whole can be made invisible. 1.0.1.3 Customizing with Configuration Files TEMPLATE menus can be customized with the use of configuration files. You can specify the label that is to appear on the menu, what program is to execute when that menu item is chosen, and optionally any necessary command parameters (the command tail, in CP/M terms). 1.0.1.4 Autoconfiguration for Turnkey Applications You can optionally create AUTOLOAD configuration files and store them on the disk with TEMPLATE. When TEMPLATE starts, it runs AUTOLOAD as part of its set up procedure. If the AUTOLOAD configuration file exists, it is loaded, saving the operator the effort, and creating a customized turnkey operation. 1.0.1.5 The DosShell (tm) Applications Interface TEMPLATE not only supports the execution of DOS commands from its master menu, it also allows guest programs to access this 4 TEMPLATE (TM) interface code. This is the DosShell -- any program, including BASIC programs, can now support a DOS command interface feature, with almost no coding overhead. 1.1 Installation of TEMPLATE 1.1.1 Distribution Files There are 4 files that you must have to run: TEMPLATE.EXE, LDMKEY.COM, LDTCFG.COM, and AUTOLOAD.COM. These are the TEMPLATE program itself, the MacroKeys loader service utility, the configuration loader service utility, and the automatic start-up configuration loader service utility. Additionally, a file named CONFIG.CFG is distributed with TEMPLATE. This is a sample configuration file that can be used to auto-configure TEMPLATE at start up time. If you are receiving TEMPLATE as a separate product, there will also be a file named TEMPLATE.DOC on the same diskette with it -- this manual! 1.1.2 Copying Execution Time Files to Another Disk All four of the executable files (programs) should be copied to the same directory on the target disk. TEMPLATE invokes the satellite modules internally, and assumes that they are in the current directory, on the current disk (i.e. current at the time of actual execution). There should always be a copy of DOS and COMMAND.COM on the diskette these files are copied to. 1.1.3 Hardware Requirements for TEMPLATE TEMPLATE runs on IBM or compatible PC's or XT's. It can operate under DOS releases 2.00 to 3.10. Although you can use it to load and run multiple programs ("stacked" execution), it is in no way a multitasking tool. TEMPLATE itself requires less than 16K of RAM, including all buffers and tables used internally. The satellite programs and utilities require RAM beyond this, and were compiled assuming a 256K address space -- therefore TEMPLATE will not operate with less than 256K of RAM. No assumption is made about what disk or diskette configuration might be used. TEMPLATE can run from any standard diskette or hard disk. COMPATIBILITY: TEMPLATE uses the interrupt vector locations assigned for user programs, at locations 60H through 67H to archive original vectors and to supply new ones. Any application that does not use these vectors can run under TEMPLATE. The MacroKeys facility intercepts BIOS requests for keyboard input (BIOS interrupt 16H) rather than fielding keyboard interrupts per se. MacroKeys support mimics original BIOS keyboard functions exactly, in addition to its key translation duties. 5 TEMPLATE (TM) Any program which does not alter this vector can run under TEMPLATE. 1.1.4 Registration for User Supported Software There is no registration fee for TEMPLATE Version 2.00. It does, however, remain the copyrighted product of Atkinson, Campbell Developement. You may copy this group of programs, collectively referred to as TEMPLATE, for your own use. You may also give away copies to anyone you choose, as long as (1) you include ALL files, particularly the documentation, and (2) you have not modified the copy you are distributing in any fashion, and (3) you have NOT received any payment for either the product, or for the act of duplicating it. Later, more advanced, versions of TEMPLATE may be distributed requesting a registration fee. If you wish, you may register your name and address with ACD (send no money). If you do, we will give you advance notice of other packages which will be user supported software registered for a fee. They will be offered to registered users at a reduced rate (which will be ridiculously low to begin with). Our later products will all be capable of being integrated under TEMPLATE, and make use of its facilities. If you want to register as a user of TEMPLATE, just send your name and address to: Atkinson, Campbell Developement 1761 Cheswood Dr. Jackson, MS 39209 1.2 Starting and Stopping TEMPLATE 1.2.1 TEMPLATE Command (Starting) When you boot your system, place the diskette containing TEMPLATE.EXE and AUTOLOAD.COM on the current drive. If you want to run in configured mode (explained below), the file CONFIG.CFG should also be present. For both floppy and hard disks, you should ideally make the directory containing these files current, although you do not have to (it is strongly recommended). To start TEMPLATE, just type that command -- TEMPLATE -- at the system prompt, and strike Return. The screen will be cleared and painted with the TEMPLATE master menu. 1.2.2 The F3 Key (Stopping) The very first thing you will want to know about is how to stop the program. Any time you can see the TEMPLATE master menu, just strike F3 and you are out. 1.3 The TEMPLATE Master Menu Screen 6 TEMPLATE (TM) The TEMPLATE master menu screen is divided into two parts. The top part, surrounded by a box, is the guest application menu. This is where you can select the programs you want to run with a single keystroke. The bottom part is the TEMPLATE control functions menu. This menu has options for controlling the behavior of TEMPLATE itself. 1.3.1 The Guest Application Menu 1.3.1.1 Unconfigured Mode "Unconfigured mode" means that you have not yet tailored the guest applications menu, picking the programs you want to integrate, and providing the menu options with labels of your choosing. Running in unconfigured mode, each time TEMPLATE presents you with the master menu screen, it will fill in the guest applications menu with the first dozen executable (.EXE or .COM) files. The file name is displayed without the extension. For example, the ARC.EXE program would be displayed simply as ARC. Note that, if a CONFIG.CFG file is present in the current directory, current disk at start up time, then TEMPLATE automatically invokes AUTOLOAD.COM (also from current disk / directory) to load the auto-configuration file and customize the guest applications menu. Creating configuration files (both for auto-configuration and in general) is described in section 1.4. You may change diskettes by simply swapping the diskette out, and striking Return to refresh the master menu screen.You may also use the DOS commands to change the current hard disk directory. In either case, be sure that there is a copy of COMMAND.COM on the new diskette or directory (and of course that the DOS system is on that disk). 1.3.1.2 Configured Mode Configured execution is much the preferrable way to run. In the first place, you can control what the labels in the guest applications menu will look like, making for a much more attractive screen. In the second place, you can (1) specify programs not in the current directory or drive, and (2) you can specify command paramters to be used when executing the program. In configured mode, you may swap diskettes out at any time without affecting the menu screen. Just be careful that the programs you want to run are still available where TEMPLATE thinks they should be. 1.3.1.3 Selecting a Guest Application to Run Since the function keys are reserved for TEMPLATE control, there has to be another way to invoke user programs via single 7 TEMPLATE (TM) keystroke. This is done with the NUMBER (not function) keys, and the letter keys A, B, and C. There will be a number or letter just to the left of each program name or menu label. If it is a number, just strike that number key across the top of the keyboard. If it is a letter, strike that CAPITALIZED letter. DO NOT strike return. The program will be loaded and run. If you strike a menu selection where there is no name or menu label, the master menu screen will be refreshed, and nothing else happens. This is also true if you strike a key (like Return) that is not used on the master menu screen. 1.3.2 The TEMPLATE Control Functions Menu 1.3.2.1 F1 - Load a Configuration File Striking the F1 key while in the TEMPLATE master menu causes the satellite program LDTCFG.COM to be loaded and executed. LDTCFG clears the screen, paints its logo, and prompts you for the name of the configuration file to be loaded. This name may contain drive and path specifications, allowing you to load a configuration file from anywhere. The example auto- configuration file CONFIG.CFG has an extension of .CFG, but this is not a requirement. It is recommended that you use this extension consistently, however, for the sake of keeping your file names straight. When LDTCFG has loaded the configuration file, the screen will be cleared again and the TEMPLATE master menu repainted. You can load a new configuration even if one is already loaded, replacing the old one. 1.3.2.2 F2 - Load a MacroKey Definition File The F2 key cause the LDMKEY.COM satellite program to be loaded and executed, similarly to loading a configuration. LDMKEY clears the screen, paints its logo, and prompts you for the name of the MacroKeys redefinition file to be loaded. You may again specify both drive and path information in this name. There is no required name format for a MacroKeys file, but it is recommended that you assign names with an extension of .KEY to avoid confusion. You can reload and overlay old MacroKeys definitions at any time. Note also that when the TEMPLATE master menu screen is showing, MacroKeys are bypassed by the TEMPLATE code. This means that you could provide a definition file that assigns redefinition strings to the Fx keys, and this will not interfere with the operation of TEMPLATE. The definition tables are fully active when any other program is being activated, including 8 TEMPLATE (TM) during the execution of DOS commands (F5 discussed below). 1.3.2.3 F3 - QUIT TEMPLATE We have already mentioned this key. F3 removes all interrupt vectors assigned by TEMPLATE and returns to the operating system. This necessarily removes all support for the MacroKeys and DosShell facilities. If TEMPLATE is not running, and you execute any of the satellite programs (AUTOLOAD, LDTCFG, LDMKEY) parts of the operating system will be overlaid -- the system will hang or crash. Also, if you have written your own program that invokes the DosShell interface, the system will hang. See the discussion on the F8 key below to discover how to terminate TEMPLATE without losing these services. 1.3.2.4 F4 - TOD Block Control The F4 key brings up the TOD Block setup screen. The TOD block is just the real time clock that TEMPLATE places in the upper right hand corner of the screen when it starts. The TOD block can be turned on or off, and can be placed anywhere on the screen. Use the arrow keys to position the TOD block where you want it. If you move the block off the screen in any direction, it will be wrapped to the other side of the screen in that same direction. You should position the TOD block where it will not be scrolled by an applications program, since it will also be refreshed by the TEMPLATE clock interrupt handler. The old copy of the clock is undetectable by TEMPLATE, so you could end up with several copies of the clock on the screen. The top right corner is generally a good place. In that position, it will not interfere with ACD's TEXT/PC word processing package, for example, or with Lotus 1-2-3 (tm Lotus Dev.). The TOD block should be turned off before running any graphics applications; it will show up as garbage on the graphics screen. 1.3.2.5 F5 - Execute Any DOS Command The title of this screen is simply "Execute Any MS-DOS Command", since you may be incorporating its use in your own code via the DosShell interface. This function loads a new copy of COMMAND.COM and gives control to it, after you have entered the command you want executed. (At the Command: prompt, type in a command just as you would at the system A>, B>, or C> prompt). Loading a new copy of COMMAND.COM works a little differently in the various versions of DOS. In DOS 3.x, you need only be sure that there is a copy of COMMAND.COM in the current drive and directory. For DOS 2.x, however, there must be a copy on the BOOT drive, ROOT directory, AS WELL as on the current drive. There is a bug in this version of DOS that does not allow DOS to properly note the change in environment strings when a new drive 9 TEMPLATE (TM) or directory is made current. 1.3.2.6 F6 - Delete Configuration Tables This key deletes all configuration data, putting TEMPLATE back into unconfigured mode. The directory of the current disk will be read, and the first 12 programs shown in the guest applications menu. 1.3.2.7 F7 - Delete MacroKey Tables Strike F7 to delete MacroKeys definitions, turning off the Macrokeys facility. MacroKeys are still available, but are simply inactive. They can be reloaded at any time with the F2 key from the TEMPLATE master menu. 1.3.2.8 F8 - HIDE TEMPLATE (Stay Resident) This is a method of terminating TEMPLATE and returning to the operating system, but leaving TEMPLATE code resident in RAM. Therefore, while the TEMPLATE master menu is no longer active, both the MacroKeys facility and the DosShell interface are. When TEMPLATE is hidden, any of the satellite utilities can be run like ordinary batch programs. For example, typing LDMKEY at the A> prompt will invoke the utility to load a new set of MacroKeys definitions. AUTOLOAD will also work in hidden mode. So will LDTCFG, but loading a new configuration when the master menu is invisible is rather meaningless. Once TEMPLATE has been hidden, it resides permanently in RAM until the next time the system is booted. 1.4 Using TEMPLATE Configuration Files 1.4.1 AUTOLOAD.COM and CONFIG.CFG Files AUTOLOAD is the satellite module that TEMPLATE invokes at start up time to load an auto-configuration file, if one exits. The name of the auto-configuration file is always assumed to be CONFIG.CFG. AUTOLOAD does not prompt for a file name. If the CONFIG.CFG file is not on the current disk, current directory, no action is taken, and TEMPLATE is left in unconfigured mode. You can provide your own CONFIG.CFG file (or any other, also), as described below. 1.4.2 LDTCFG.COM and Configuration Files LDTCFG is the satellite program that is invoked, when you strike F1 on the master menu, to load any other configuration files than the CONFIG.CFG file. These other files do not have to have any particular file name. 10 TEMPLATE (TM) Unlike AUTOLOAD, LDTCFG does prompt you for the name of the configuration file to be loaded, as noted above. 1.4.3 Structure of .CFG Files .CFG files are ASCII text files. They can be composed of up to 12 lines of text, each followed by a CR/LF pair of characters; that is, standard text files according to DOS definition of the term. A .CFG file also ordinarily has an end of file marker (control-Z, ASCII 26 decimal) at its end. You can create .CFG files with any STANDARD word processor or line editor; that is one which you can prevent from embedding special control characters in the text, and does not turn on the high bit of any byte. You could use the DOS EDLIN utility, ACD's TEXT/PC word processor, or the editor in the Turbo Pascal package, for example. 1.4.3 Syntax of Configuration Statements An individual line in a configuration file, or configuration statement, is just a string of characters that logically has two parts: the menu label and the corresponding executable program name. Optionally, command parameters needed by the program may follow the first two parts. The order of appearance in the configuration file determines where a menu label will appear in the guest applications menu. That is, the first line will be selection 1, and so forth. For example, imagine a program named MOVEFILE.COM. Here is how we could define its appearance for the guest applications menu: Move File 1 to File 2=c:movefile.com a:file1.doc b:file2.doc The configuration statement begins with the substring "Move File 1 to File 2". This is the menu label, and is what will appear on the menu screen. The menu label may be up to 30 characters long, and must be at least 1 character long. The equals sign = now tells LDTCFG that the actual program specification follows. Notice that there is NO blank preceding and NO blank following the =. Next we have the executable program specification. It is to be loaded from the C: drive, whether this is the current drive or not. In this case, it will be loaded from the current directory on C:, but we could have also specified path information. NOTICE that the EXTENSION IS PRESENT. During the loading of the program module it is treated like any other file; therefore leaving off the extension would cause a mismatch during the directory search for the program. Finally, the command parameters (command tail) appears, with 11 TEMPLATE (TM) blanks embedded right where they would be if you were running the program from the system prompt. Code these parameters just like you would any other time. The following example is the CONFIG.CFG file supplied with TEMPLATE. Its purpose is to auto- configure the TEXT/PC package from Atkinson, Campbell Dev.: TEXT/PC Word Processor=a:wp.com TYPESET/PC Document Printer=a:typeset.com FONT/PC Graphics Font Editor=a:gcg.com COMM/PC Asynchronous Comm.=a:comm.com CP/PC Compress a File=a:cp.com DC/PC Decompress a File=a:dc.com Monochrome Font Editor=a:ged.com Font Report / Print=a:grep.com This configuration file will provide labels for the first 8 guest application menu selections. 1.5 Using the MacroKeys Facility 1.5.1 LDMKEY.COM Utility LDMKEY is the satellite program invoked when you strike F2 on the TEMPLATE master menu screen. It will first ask you for the name of the .KEY file to be loaded, and then use that file to redefine the current MacroKeys definitions. LDMKEY can also be run from the DOS commands screen (see F5 key discussion above). This is mentioned since a program utilizing the DosShell interface may also wish to reload MacroKeys during its execution. That is the only way to do this from a program that you have written. Lastly, LDMKEY can be run from the system prompt when TEMPLATE has been placed into hidden mode. In all cases where you invoke it directly, just type in the name LDMKEY and strike Return, providing no command tail. 1.5.2 Structure of .KEY Files .KEY files do not have to have this extension; it is merely recommended as a standard name for them. .KEY files are similar to configuration files in that they are standard ASCII text files. They are different in that they may have many more than 12 statements, as long as the total size of the translation table does not exceed 4096 bytes. They are also different in that the order of specification makes no difference, since the key being redefined is identified in the statement. However, it is a good idea to define frequently used keys near the top, to reduce search time for the substitution string. MacroKey redefinition statements also consist of two parts: the identity of the key being redefined, and the string of characters that is to be used as keyboard input in its place. 12 TEMPLATE (TM) In order to support both the redefinition and input of the special keys on the keyboard, we will make provision for specifying Extended ASCII codes. Extended ASCII codes are codes beyond the 256 different values that can be specified in a single byte. Consequently, an Extended ASCII code requires two byte to completely specify it. These two bytes are called the character code and the scan code. Confused? Here is what we mean. When a program, including the DOS routines themselves, request keyboard input from the ROM BIOS I/O handlers, the BIOS routine always returns two bytes -- the character and scan codes. For ordinary keys, the character and scan codes are exactly the same, so that 256 different values are possible. For example, the character "A" is represented by two bytes each containing an ASCII 65 (decimal); the Escape key is represented by two bytes each containing 27 (decimal). However, if you strike the F1 key, the two bytes returned to the program are different. This time the character code is an ASCII 0, signalling that the scan code contains an Extended ASCII code. For the F1 key, the scan code is 59 (decimal). Here is a complete table of the special keys that require an Extended ASCII code to identify them, citing only the scan code (assuming a 0 character code): Extended ASCII Keystroke Description (Second) Code ------------------------------------------------------ 3 NUL (CTL-@, = Shift-Ctl-2) 15 Shift (back) Tab 16-25 Alt - Q,W,E,R,T,Y,U,I,O,P 30-38 Alt - A,S,D,F,G,H,J,K,L 44-50 Alt - Z,X,C,V,B,N,M 59-68 F1 thru F10 71 Home 72 Cursor Up (Arrow) 73 Page Up 75 Cursor Left (Arrow) 77 Cursor Right (Arrow) 79 End 80 Cursor Down (Arrow) 81 Page Down 82 Ins (Insert) 83 Del (Delete) 84-93 Shift - F1 thru F10 94-103 CTL - F1 thru F10 104-113 Alt - F1 thru F10 114 CTL - PrtSc 115 CTL - Cursor Left 116 CTL - Cursor Right 117 CTL - End 118 CTL - Page Down 119 CTL - Home 13 TEMPLATE (TM) 120-131 Alt - 1,2,3,4,5,6,7,8,9,0,-,= 132 CTL - Page Up ---------------------------------------------------------- 1.5.3 Syntax of MacroKey Redefinition Statements Now we have the terminology to discuss the syntax of a MacroKeys definition statement. In general, a MacroKeys redefinition statement may contain 255 characters of data, maximum; a statement may not be null; it must be terminated by a true carriage return / line feed pair of characters. The component elements of the string of characters utilize the Turbo Pascal syntactical standard for string constant specification. This means that the characters #, ^, and ' (single quote) have special significance, as follows: The # character begins a 1 to 3 digit decimal number specification that will be parsed (decoded) into a byte type numeric field. That is, #255 will parse internally into a 1 byte item that has an ASCII value of 255 decimal. The ^ character means that a control character follows. For example, ^M means that the parser is to generate a byte field whose ASCII value is the same as the control-M key (77-64=13). This example was chosen for a special reason: since you have to end the text line with a real CR/LF, this is how you would specify the Return key action in a redefinition statement. You should also be very careful to note that it is usually the software that automatically supplies the LF character; you would almost never have to code a ^J in a statement. The ' single quote character delimits normal text strings, like this; 'This is a normal text string'. There is a single quote on each end of the string. If you need a single quote as data inside the string, just double it up (not a double quote, just two singles): 'This isn''t very hard.' There are some instances where the single quotes can be left out, but that is a nonstandard use, and may change with new versions of TEMPLATE Therefore, you should always use the single quotes when they are called for. To create the whole MacroKeys redefinition statement, just string together elements of these three kinds; do not use embedded blanks unless you want them to actually be part of the specification, and do not separate elements with commas or anything else -- run it all together. For example, let's say that we want the F1 key to be translated to "Hello, there." and supply that string for input to the program requesting keyboard input. Here is how we would code this: #0#59'Hello, there.' 14 TEMPLATE (TM) Here we have a character code of 0 followed by a scan code of 59; this identifies the F1 key as the one being redefined. THE KEY BEING REDEFINED IS ALWAYS SPECIFIED WITH BOTH THE CHARACTER AND SCAN CODES, IN THAT ORDER. Next we have a substring of normal characters enclosed in single quotes. Since they are normal characters, they do NOT have to have both character and scan codes. For a more complex example, assume that you are running a database program in which you strike the Esc key to pop up a commands menu. On this menu, F1 selects a search by keyword, which in turn will then prompt you to supply that keyword for the search operation, followed by striking the Return key. We want to search for records containing the chatacters "keyboard". Finally, assume that we want the Esc key to do all that work for us. Here is the MacroKeys statement for it: #27#27^[#0#59'keyboard'^M The specification #27#27 identifies the Esc key as the one being redefined. Since it is a normal, not an Extended ASCII, character we just specify the same code twice. Both the character and scan codes are the same for normal characters. Next we see ^[ encoded. This is just the Esc key again! Learn two things from this: (1) There is more than one way to encode some keys. Consult your ASCII charts to see what can be done. (2) MacroKeys references are NON-RECURSIVE. You can redefine a key, and then use it within the redefinition statement. In this case, the Esc character will actually be passed on to our hypothetical database program. The F1 key is encoded with #0#59. Here is a very important rule: ANY KEY WHICH HAS A CHARACTER CODE OF 0 -- A SPECIAL OR FUNCTION KEY AS FOUND IN THE TABLE ABOVE -- MUST BE SPECIFIED WITH BOTH THE CHARACTER AND SCAN CODES, IN THAT ORDER. THIS IS TRUE WHEREVER IT APPEARS IN THE REDEFINITION STATEMENT. To specify the keyword for search, we code 'keyboard'^M. This causes both the keyword and a carriage return to be passed to the program. The real CR that we struck while editing the MacroKeys file is not part of the redefinition. 1.5.4 Advanced Use of MacroKey Definitions A word of caution is in order. Because MacroKeys redefinition statements are non-recursive, you can redefine keys that a program assumes are present, IF you assign other keys their original function. For example, TEXT/PC assumes that F1 - F10 are reserved for use by the word processor itself. You could define F1 - F10 as MacroKeys, if you assigned, say, Alt-1 through Alt-10 to input F1 - F10. But this is confusing and is best avoided. The TEXT/PC package has with it MacroKeys definitions that are invoked by 15 TEMPLATE (TM) the shifted function keys, S-F1 through S-F10. 1.6 Programming the DosShell Interface 1.6.1 Theory Behind the DosShell Interface The DosShell interface is a method with which a program you write can access the same code that TEMPLATE uses to execute DOS commands from within the application program. With this interface, you can provide a service to the user usually only found in very expensive packages. The interface is accessed by executing interrupt 63 Hex. TEMPLATE sets up the interrupt vector; all you have to do is execute the 8088 interrupt (INT) instruction. You can do this from BASIC, Turbo Pascal, assembler routines, or any language which can execute this machine instruction directly (by whatever method). 1.6.2 Programming Requirements 1.6.2.1 Screen Disposition During Execution When you invoke the DosShell, you get the same screen as when you strike F5 from the TEMPLATE master menu. Anything you had on the screen already is destroyed, so it is your program's responsibility to preserve it if necessary. Once the DosShell has executed the user's command, control is given back to your program, but the screen is not cleaned up for you. If you had preserved the original screen, you can restore it; if not, you must repaint it. 1.6.2.2 Invoking Interrupt 63H(ex) It requires only two bytes of machine code to invoke the DosShell via interrupt 63H. The interrupt instruction is CDH, and the interrupt id is 63H. Your program need NOT make any provisions for preserving the PC's registers. The DosShell will save and restore every register in the system on your behalf. 1.6.2.3 RAM Requirements, System and User When you invoke the DosShell from a program, the TEMPLATE code is naturally already present. But the interface begins its operation by loading a secondary copy of COMMAND.COM from the current disk and directory (see notes above about exceptions for DOS 2.x). For DOS 2.10, this requires about 17K extra RAM; for 3.10 it requires about 24K. Once COMMAND.COM is loaded, it in turn may need to load a utility program. The amount of RAM required varies with the utility, but many will run on a 256K system. If you have sufficient RAM you may even run a DOS batch file from the DosShell. 16 TEMPLATE (TM) 1.6.3 Invoking From Assembler Routines It requires only one line of code to invoke the DosShell from an assembler routine: INT 63H ; GOTO DOSSHELL You need not push or pop registers; the interface does it for you. There are no special considerations or odd conditions to handle in assembler routines. You should, however, use the DOS SHRINK call to free up enough RAM to hold COMMAND.COM and whatever routines it will invoke. 1.6.4 Invoking From Turbo Pascal The Intr procedure in Turbo Pascal IS NOT APPROPRIATE for invoking the DosShell. That procedure does too many things to the system registers, and will likely hang the system if you try it. Instead, use inline code to do it: inline($CD/$63); is all you need. Again, you need not save registers. You must, however, set compile options so that the .COM file does not take over all of RAM; there would be no place to load COMMAND.COM then. See the Turbo Pascal reference manual for details. 1.6.5 Invoking From BASIC/BASICA The following example is only one method of poking a machine language routine into memory and invoking the DosShell. Consult the BASIC manual for other methods; the routine stays the same whatever the method. 10 CLEAR ,&HFFF8 20 POKE &HFFF8,&HCD: POKE &HFFF9,&H63: POKE &HFFFA,&HCB 30 DOS=&HFFF8 40 CALL DOS: CLS Line 10 clears BASIC's user area of garbage and reserves 8 bytes of spaces at its high end. This is where we will poke our short machine language routine. Line 20 actually pokes the routine. The first values you are already familiar with; a hex CB is an 8088 long return, no parameters. This is necessary to go back to the point after the call statement properly. Line 30 merely equates offset &HFFF8 with the label DOS. Notice that we have not used the DEF SEG statement, so that we are still working within the user area of BASIC. Line 40, finally, actually calls the machine language 17 TEMPLATE (TM) routine, which in turn invokes the DosShell within TEMPLATE. On return from the DosShell, a BASIC clear screen is executed. You can replace the CLS with whatever you want. 1.6.6 Stacking Applications in RAM with the DosShell Consider the situation in which your program was invoked from the GUEST APPLICATION MENU. While your program is running, you decide that you want to run a Lotus 1-2-3 spreadsheet, so you invoke the DosShell with your program's facility. At the Command: prompt you type in 123 and strike return. And away you go. When you terminate the spreadsheet, then you are right back in your program, nothing lost or damaged. This is called "applications stacking." It allows you to have more than one application program active in RAM at a time, but (1) since they weren't both started by the DosShell, no nonreentrant code violations occurred, and (2) since they aren't running concurrently, there is no confusion over multitasking conditions. If you start a program with TEMPLATE's DOS command facility, however, and then attempt to invoke the DosShell from that program, you will have reentered nonreentrant code. The result will be that the system will hang when you return to the TEMPLATE master menu. That's TEMPLATE. Please let us know how you like it. We plan to listen to the users before designing the next release. 18